esbuild-plugin-alias

What is esbuild-plugin-alias?

The esbuild-plugin-alias package is a plugin for esbuild, a fast JavaScript bundler and minifier. This plugin allows users to configure custom path aliases for modules in their project, which can simplify imports and make them more readable. It can also be used to mock modules or bind to specific versions of a module.

What are esbuild-plugin-alias's main functionalities?

Path Aliasing

This feature allows you to replace module paths with aliases. In the code sample, 'react' and 'react-dom' are aliased to 'preact/compat', which means that anywhere 'react' or 'react-dom' are imported, 'preact/compat' will be used instead.

require('esbuild').build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    require('esbuild-plugin-alias')({
      react: require.resolve('preact/compat'),
      'react-dom': require.resolve('preact/compat')
    })
  ]
});

Directory Aliasing

This feature allows you to create aliases for directories. In the code sample, 'components' and 'utils' are aliases for the './src/components' and './src/utils' directories, respectively. This makes importing from these directories shorter and cleaner.

require('esbuild').build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    require('esbuild-plugin-alias')({
      components: './src/components',
      utils: './src/utils'
    })
  ]
});

Other packages similar to esbuild-plugin-alias

babel-plugin-module-resolver

This Babel plugin allows you to add new 'root' directories that contain your modules. It also allows you to alias directories and specific files, similar to esbuild-plugin-alias. However, it is used within the Babel ecosystem and not directly with esbuild.

rollup-plugin-alias

rollup-plugin-alias is a plugin for Rollup, yet another module bundler. It offers similar aliasing capabilities as esbuild-plugin-alias, allowing you to define aliases for modules in your Rollup configuration. It is specific to Rollup and is an alternative to esbuild-plugin-alias for projects using Rollup as their bundler.

README

esbuild-plugin-alias

esbuild plugin for path aliases.

Rationale

Sometimes it's useful to have dynamic imports that resolves into different files depending on some conditions (e.g. env variables).

Installation

npm install --save-dev esbuild-plugin-alias

Usage

Define plugin in the plugins section of esbuild config like this:

const esbuild = require('esbuild');
const alias = require('esbuild-plugin-alias');

esbuild.build({
  // ...
  plugins: [
    alias({
      'imported-path': '/home/user/lib/src/resolved-path',
    }),
  ],
})

Note: esbuild requires resolved paths to be absolute. So, make sure that values in plugin's config object are absolute paths.

If you need to find a path to an installed dep, you may use require.resolve. E.g.:

alias({
  'react-dom': process.env.NODE_ENV === 'dev' 
    ? require.resolve('@hot-loader/react-dom')
    : require.resolve('react-dom'),
}),

Example

Having this input file:

// src/app.js
import settings from 'settings.env';

console.log(settings);

And esbuild config like this:

// config/build.js
const path = require('path');
const esbuild = require('esbuild');
const alias = require('esbuild-plugin-alias');

esbuild.build({
  entryPoints: ['in.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    alias({
      'settings.env': path.resolve(__dirname, `../src/settings.${process.env.NODE_ENV}.js`),
    }),
  ],
}).catch(err => process.exit(1));

You will get src/settings.dev.js loaded instead of settings.env when NODE_ENV equals dev.

Check test/ for more detailed example.